import { Callout } from '@/components'

# Support both TanStack Query v4 and 5

<Callout type='info'>

From version 2.2.0 onwards, @tanstack/react-query supports both v4 and v5. To support older browser versions, use @suspensive/react-query with @tanstack/react-query v4.

</Callout>

<Callout type='warning'>

**Deprecated Backported Interfaces in TanStack Query v4**

Starting from TanStack Query v4.40.0 and v4.41.0, several interfaces that were previously backported by @suspensive/react-query are now officially supported in TanStack Query itself. These backported interfaces are now deprecated and will be removed in future versions.

**Deprecated interfaces:**

- `queryOptions` (available since v4.40.0)
- `infiniteQueryOptions` (available since v4.41.0)
- `useSuspenseQuery`, `useSuspenseQueries`, `useSuspenseInfiniteQuery` (available since v4.40.0)
- `SuspenseQueriesOptions`, `SuspenseQueriesResults` (available since v4.40.0)
- `UseSuspenseQueryOptions`, `UseSuspenseQueryResult` (available since v4.40.0)

**Migration required:** If you're using TanStack Query v4.40.0+ or v4.41.0+, please migrate to the official TanStack Query interfaces instead of the backported ones from @suspensive/react-query.

</Callout>

@suspensive/react-query is composed of @suspensive/react-query-4 and @suspensive/react-query-5, which provide interfaces corresponding to the version of @tanstack/react-query. It detects the installed version of @tanstack/react-query in the user's environment and automatically provides the compatible interface.

## Command-Line Interface (CLI)

The Command-Line Interface (CLI) of @suspensive/react-query is a tool to match compatibility with @tanstack/react-query. It allows you to check the compatibility with the installed version of @tanstack/react-query and switch the interface of @suspensive/react-query to a compatible one via commands.

However, in most cases, the CLI is rarely needed as @suspensive/react-query automatically provides a compatible interface based on the installed version of @tanstack/react-query upon installation.

## Getting Started

The CLI is included with the @suspensive/react-query package. No additional installation is required. You can use it directly with the following command.

```bash
npx suspensive-react-query
```

Or simply use `srq`.

```bash
npx srq
```

## Commands

The CLI currently offers 5 commands. Here are the descriptions of each command.

| Command | Description                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| version | Displays the currently installed version of @suspensive/react-query.                                                                     |
| help    | Shows usage information for the commands.                                                                                                |
| status  | Checks compatibility with the currently used version of @tanstack/react-query.                                                           |
| switch  | Switches the exports of @suspensive/react-query to use the interface compatible with the version of @tanstack/react-query.               |
| fix     | Automatically switches the exports of @suspensive/react-query to use the interface compatible with the version of @tanstack/react-query. |

### version

Displays the installed version of @suspensive/react-query. This reflects the package version specified in `package.json` and does not indicate the version of @suspensive/react-query-4 or @suspensive/react-query-5 internally configured for compatibility with @tanstack/react-query.

```bash
npx suspensive-react-query -v
```

Or

```bash
npx suspensive-react-query --version
```

### help

Provides usage information for commands in the console. For example, to learn more about the `fix` command, use.

```bash
npx suspensive-react-query fix -h
```

Or

```bash
npx suspensive-react-query --help
```

### status

You can check the compatibility status between the installed versions of @tanstack/react-query and @suspensive/react-query in your current environment. Additionally, you can see which interfaces are available for use in the current environment from the list of available interfaces.

```bash
npx suspensive-react-query status
```

For example, using @suspensive/react-query@2.12.1 and @tanstack/react-query@5.51.21, the result might be.

```
┌─────────────────────────────────────────┬──────────┬────────────────────────────────────┐
│ @suspensive/react-query@2.12.1          │ status   │ available interfaces               │
├──────────┬──────────────────────────────┼──────────┼────────────────────────────────────┤
│ exports  │ @suspensive/react-query-5    │ 🟢       │ SuspenseQuery SuspenseQueries      │
│ from     │ @2.12.1                      │          │ SuspenseInfiniteQuery              │
│          │                              │          │ QueryErrorBoundary Mutation        │
│          ├──────────────────────────────┼──────────┼────────────────────────────────────┤
│          │ @tanstack/react-query        │ 🟢       │ useSuspenseQuery                   │
│          │ @5.51.21                     │          │ useSuspenseQueries                 │
│          │                              │          │ useSuspenseInfiniteQuery           │
│          │                              │          │ queryOptions infiniteQueryOptions  │
└──────────┴──────────────────────────────┴──────────┴────────────────────────────────────┘
```

### switch

Switches the exports of @suspensive/react-query to use the interface compatible with the installed version of @tanstack/react-query. This updates the entry file (dist/index.js) of @suspensive/react-query.

```typescript
// dist/index.js of @suspensive/react-query

// When you use "npx suspensive-react-query switch 4"
// @suspensive/react-query's dist/index.js
export * from '@suspensive/react-query-4' // Suspensive interfaces for @tanstack/react-query@4
// When you use "npx suspensive-react-query switch 5"
// @suspensive/react-query's dist/index.js
export * from '@suspensive/react-query-5' // Suspensive interfaces for @tanstack/react-query@5
```

If you are using @tanstack/react-query v5 and encounter errors, you can update the entry file (dist/index.js) and switch to the compatible interface by using the following command.

```bash
npx suspensive-react-query switch 5
```

### fix

The `fix` command is a convenient way to match versions in an environment where @suspensive/react-query and @tanstack/react-query are incompatible. It automatically switches the exports of @suspensive/react-query to use the interface compatible with the installed version of @tanstack/react-query.

```bash
npx suspensive-react-query fix
```

## Troubleshooting

If you encounter errors related to @suspensive/react-query during build, it is likely due to compatibility issues with the installed @tanstack/react-query version.

You can specify the version in `package.json` to ensure the correct version is used during build. For example, to automatically use the correct version, you can use the following script.

```json
{
  "scripts": {
    "build": "suspensive-react-query fix && next build"
  }
}
```

Or to fix the version, set it up as follows,

```json
{
  "scripts": {
    "build": "suspensive-react-query switch 5 && next build"
  }
}
```
